================================================================
  DAoC STREAM OVERLAY - START HERE
  The whole setup, explained for someone who has never done it.
================================================================

Nothing here needs any programming. There is no installer, no
account, and nothing to configure. If you can add a webcam to OBS,
you can do this.

Read the steps in order. Each one ends with WHAT YOU SHOULD SEE,
so you always know whether it worked before moving on.

Once it is set up you never read this again except for the last
two parts: TEN MINUTES BEFORE YOU GO LIVE, which is the check to
run before each stream, and IT IS NOT WORKING.


----------------------------------------------------------------
WHAT THIS IS, IN ONE PARAGRAPH
----------------------------------------------------------------

Dark Age of Camelot can write everything in your chat window to a
text file. This program reads that file while you play, adds the
numbers up, and turns them into little scoreboards you can put on
your stream: realm points, damage, kills, and so on. They update
themselves while you play.

The scoreboard part only reads that text file. It changes nothing
in the game and reaches nothing else.

The flusher is the one part that talks to the game, and you turn
it on yourself. Here, plainly, is what it does. It reads a little
of what the game already knows about your own character - your
name, your zone, your realm rank - and it tells the game to write
its chat log the instant something happens, so your numbers never
sit still. That last part is a small, temporary nudge to the game
while it is running: it changes nothing the game keeps on disk,
and it undoes itself the moment you close the game. (An older
backup way just taps your chat-log key on a timer instead, for
game versions it cannot read.) Because it looks at and nudges the
running game - which itself runs with administrator rights -
Windows asks you once to allow it. Nothing leaves your PC, and the
overlay works fine with the flusher left off.

Three extra things it can do if you want them, all switched off
until you switch them on: drive OBS or Streamlabs for you
(step 9), answer
commands in your Twitch chat (step 10), and look your lifetime
realm points up so it can tell you your realm rank (step 11).
Steps 1 to 5 are the whole program without any of that.


----------------------------------------------------------------
WHAT YOU NEED
----------------------------------------------------------------

  * Windows
  * Dark Age of Camelot (official servers)
  * OBS Studio or Streamlabs - only if you want it on stream.
    You can use this without OBS at all; see step 8.

You do NOT need Python, a terminal, admin rights, or any
"runtime". The download is one program and a couple of text
files.


----------------------------------------------------------------
STEP 1 - UNZIP IT
----------------------------------------------------------------

Right-click the file you downloaded and choose "Extract All...",
then pick somewhere easy to find. Your Desktop is fine.

Do not run it from inside the zip. Windows opens zip files like
folders, which makes it look like you can - but programs run from
in there behave oddly and cannot save their settings.

WHAT YOU SHOULD SEE: a folder with overlay.exe, this file, and
README.md in it.


----------------------------------------------------------------
STEP 2 - RUN overlay.exe
----------------------------------------------------------------

Double-click overlay.exe.

Windows will interrupt you twice. Both are normal, and neither
means anything is wrong:

  1. A blue box saying "Windows protected your PC".
     Click "More info", then "Run anyway".

     Why: Windows shows this for any program that has not paid
     for a code-signing certificate. They cost a few hundred
     pounds a year. It is not a virus warning, and it says
     nothing about what the program does.

  2. "Allow this app through the firewall?"
     Tick "Private networks" and allow it.

     Why: OBS talks to this program over your own network. If OBS
     is on the SAME PC you can decline this and everything still
     works. If OBS is on a SECOND PC, you need to allow it.

YOUR ANTIVIRUS MAY ALSO OBJECT. The name it gives will be
something like "Wacatac" or "Obfuscator", often ending in "!ml".

That ending means a computer guessed. None of those names is a
real piece of malware anyone has found in this; they are the
labels a scanner uses for a file it cannot identify, and this
one is hard to identify for two boring reasons:

  - Nothing here is signed, for the same reason as the blue box
    above. A scanner has no publisher to check, so it guesses.
  - The flusher sends one keypress to the game window on a
    timer. That IS what a scanner watches for, and it is also
    the only reason the flusher exists - see step 6. It is part
    of overlay.exe, so a scanner looking at overlay.exe can see
    it whether or not you ever turn it on.

If you would rather not take that on trust:

  - Check the file against SHA256SUMS, which came with the
    download. In PowerShell:
        Get-FileHash .\overlay.exe -Algorithm SHA256
  - Or leave the flusher switched off. It never runs unless you
    turn it on in step 6. Everything still works; the numbers
    just update more slowly.
  - Or build it yourself from the source. The README says how.

If you decide it is fine, restore it in Windows Security ->
Protection history -> Allow, and add the folder under
Exclusions.

A black window opens with some text and a list of web addresses.
Leave it open - that IS the program. Closing it stops everything.

WHAT YOU SHOULD SEE: a list of addresses beginning with
http://localhost:8752/ and a line saying where it found your
chat.log.


----------------------------------------------------------------
STEP 3 - TURN THE CHAT LOG ON, IN GAME
----------------------------------------------------------------

This is the step everybody gets half-right. There are TWO parts,
and doing only the first is the number one reason an overlay
shows nothing but zeroes.

PART A - tell the game to write the file.

  Log in, click on the chat box, and type this, exactly:

      /chatlog

  Press Enter. That is all. It stays on from then on, including
  after you close the game, until you type it again to turn it
  off.

  Type it on its own. If you type /chatlog something the game
  writes to a differently-named file, and the overlay will not
  find it.

PART B - tell the game WHAT to write.

  Right-click on your chat tab (the little tab above the chat
  box, usually called "Main"). Choose "Messages & Channels".

  A window opens with a long list of Message Types, each with a
  tickbox. TICK ALL 16.

  Why this matters: the log gets written either way, but only the
  types you ticked ever go into it. If Combat is unticked, none
  of your damage is written down, so the overlay counts zero
  damage - and it looks broken when it is actually doing exactly
  what it was told.

WHAT YOU SHOULD SEE: nothing yet, in game. Step 5 checks it.


----------------------------------------------------------------
STEP 4 - PUT A SCOREBOARD ON YOUR STREAM
----------------------------------------------------------------

In OBS (Streamlabs is nearly identical):

  1. In the Sources box at the bottom, click the + button.
  2. Choose "Browser".
  3. Give it a name, like "DAoC stats". Click OK.
  4. In the URL box, delete what is there and paste ONE of the
     addresses the black window printed. Start with:

         http://localhost:8752/w/all

  5. Set Width 400 and Height 600. You can change this later.
  6. Click OK.

The scoreboard appears in your scene. Drag it where you want it,
and drag its corners to resize.

The background is see-through on purpose - only the text shows
over your gameplay.

The addresses, and what each one shows:

  /w/all       everything at once
  /w/rp        realm points, RP per hour, deaths
  /w/combat    damage, DPS, hit rate, who you fought
  /w/pve       XP per hour, coin, kills, level, zone
  /w/killfeed  your kills as they happen, with RP earned
  /w/realm     what your realm's frontier is doing
  /w/cc        crowd control you landed, and on whom
  /w/alert     a big moment for a few seconds, then blank again

You can add several. Each is its own source, positioned
separately - that is how you build a layout you like.

WHAT YOU SHOULD SEE: a scoreboard in your OBS preview. All zeroes
is CORRECT until you have played a little with the log on.


----------------------------------------------------------------
STEP 5 - CHECK IT IS ACTUALLY WORKING
----------------------------------------------------------------

Open this address in any web browser on the gaming PC:

    http://localhost:8752/

That page tells you, in plain words, whether the overlay is
healthy. It says one of four things:

  "Working"
      Good. Nothing to do.

  "No chat.log found"
      The game has never written the file. Go back to step 3
      part A and type /chatlog in game.

  "Log found, but nothing is being written"
      The file exists but has not changed for a while. Either you
      are not in game, or /chatlog got switched off. Type it
      again.

  "Log is growing, but nothing in it counts"
      This is the 16-tickbox problem. Go back to step 3 part B.

The scoreboards themselves also carry a small status line saying
whether the numbers are live or lagging. You can hide that line -
see step 7.


----------------------------------------------------------------
STEP 6 - MAKE THE NUMBERS MOVE SMOOTHLY (OPTIONAL)
----------------------------------------------------------------

The game does not write to the log the moment something happens.
It fills a small buffer first and only writes when that buffer is
full. On a quiet solo evening that can mean your numbers sit
still for a few minutes and then jump all at once.

The flusher fixes that.

TURN IT ON FROM THE SETTINGS PAGE (step 7). There is a Start
button beside the flusher settings, and a tickbox "Start it with
the overlay". Tick that and you never think about it again: it
starts when the overlay starts, stops when it stops, and what it
prints appears on that page. There is no second window, which is
the point.

It is part of overlay.exe rather than a separate download, but it
runs as a program of its own when it is on. That is deliberate:
it is the only part that presses a key, and the only part that
ever asks for administrator rights. The overlay itself never does
either.

What it does, by default: it reads your character, zone and realm
rank from the running game, and tells the game to write each chat
line the moment it happens, so your numbers keep up instead of
arriving in bunches. That is a small, temporary nudge to the game
while it runs, and it undoes itself when you close the game. If it
meets a game version it cannot read, it falls back on its own to
tapping your chat-log key on a timer, which has the same effect.

ONE EXTRA IT CAN DO. Beside the flusher settings is a tickbox
"Play game sound while it is not the focused window". Tick it and
the game keeps making sound when you tab away to watch chat or
your stream. Like the real-time log, it is a small, temporary
change to the running game that undoes itself when you close it -
nothing on disk is touched.

WINDOWS WILL ASK "do you want to allow this app to make changes".
Say yes. The game itself runs with administrator rights, and
Windows will not let a normal program read or nudge it without the
same - and it refuses quietly, so the flusher would look like it
is working while your numbers never move. Administrator rights are
what get past that. Say no and it carries on anyway, which is fine
if your DAoC is not running as administrator.

It reopens in its own window when you say yes. That is the same
program with the rights it asked for, so watch that window from
then on: the settings page can no longer read what it prints. The
page can still stop it, and it still closes when the overlay does
- including when you end the overlay from Task Manager, or it
crashes. It never keeps typing into the game once the overlay it
came with is gone.

For it to work you need /chatlog on a keybind:
  Options -> Keyboard, find the chat log toggle, and bind it to a
  key you do not otherwise use.

ONE OTHER KEY, IF YOU WANT IT. The settings page has a "/stats
key" box, filled in with \. Your chat log never states your death
count or your deathblows, so the flusher can press a quickbar slot
holding /macro stats /stats and read the answer out of the log.
(Your zone and realm rank it reads from the game directly, so no
key is pressed for those.)

  That slot has to hold that macro. A quickbar key presses
  whatever is on it, so if \ holds a spell, that is what gets
  cast, every few minutes, on stream. Put the macro there or
  empty the box - empty means that key is never pressed.

overlay.exe -flush -add-stats-macro <yourcharacter> writes the
macro onto a free slot for you and tells you which key it used.

  The flusher checks this on every start and prints a line per
  key - which character has the macro on it, and a warning if
  nobody does. Read what it prints the first time you start it.

The flusher prints what it found and whether the key is working,
on the settings page. If it says NOT ACTIVE, read the note it
prints - it names the setting to change.

You can skip this entirely. The scoreboards say "buffered" when
you have, which is a statement of fact rather than an error.


----------------------------------------------------------------
STEP 7 - CHOOSE WHAT EACH SCOREBOARD SHOWS
----------------------------------------------------------------

Open this in a browser on the gaming PC:

    http://localhost:8752/control

This is the settings page. You can:

  * pick a widget from the dropdown and untick any row you do not
    want on screen
  * set how many rows the lists show
  * tick "Hide the state line" to remove the small
    live / buffered / log-stopped text at the bottom of a
    scoreboard
  * copy the finished address to paste into OBS

About "Hide the state line": tick it if you want nothing on your
scene but numbers. It stays hidden in every situation, including
if the overlay stops - the scoreboard will simply freeze rather
than announce anything to your viewers.

That is the trade. With the line visible you get a warning when
your log stops; with it hidden you get a clean scene and no
warning. A good middle ground is to hide it on your big
scoreboards and leave it visible on one small one.

Every change gives you a new address. Paste it back into the OBS
browser source (double-click the source, replace the URL).

COLOURS AND FONT

Under "How it looks" you pick the text colour, the colour of the
labels, the colour of the numbers, the backdrop and how
see-through it is, the font and the size.

That one setting covers every scoreboard AND the HUD over your
game. You do not have to re-add anything in OBS: a browser source
picks the change up within a few seconds on its own.

Two things worth knowing. The font list is a shortcut, not a
limit - anything installed on this PC works, so type the name. And
"see-through" is the panel BEHIND the numbers, so it does nothing
on a source with the solid background left off, which is how most
people run them.


MOMENTS

The /w/alert scoreboard is different from the others. It is blank
almost all the time. When something big happens it shows one line
for six seconds, then goes blank again.

Seven things count as big:

  * you cross a realm rank
  * five enemy players killed without dying, then ten, then every ten
  * five mobs killed without dying, then ten, then every ten
  * tonight passes your best night so far
  * you level
  * a keep or tower is taken
  * you die

Add it like any other browser source, put it somewhere your
gameplay is not, and leave it. Under "Browser sources" on the
control page, pick "alert" and you get three extra choices: how
long it stays up, which of these it shows, and whether it plays
a short sound.

Realm rank comes from one of two places. With the real-time log
running (the flusher, which reads the game), your rank AND your
exact lifetime realm points are read straight from the client - so
the rank moment fires the instant you gain a realm level, and !rp
and the rank bar are right too, with no lookup. Failing that,
step 11 (Lifetime realm points, the Herald) supplies the total the
slower way. With neither, it stays quiet rather than guess.

Realm rank 15 is the top - there is nothing above it. On 15L0 the
rank bar goes away instead of sitting full, and !rp says so.

CHAPTER MARKERS FOR YOUR VOD

On the control page, under "Moments", tick "Write chapter markers
for the VOD". Every moment above is then also written to a file
called chapters.txt, next to overlay.exe, looking like this:

  1:42:10 Realm Rank 6 -- realm rank 6L0
  2:03:55 10 in a row

Paste that under your video and YouTube and Twitch both turn it
into a clickable list of chapters. The times are counted from when
overlay.exe started. If you started recording at some other
moment, line the first marker up with your video and move all of
them by the same amount. The file starts fresh each time you run
overlay.exe.

PAST NIGHTS

Under "Past sessions" the control page lists your last twenty
evenings - RP, RP per hour, kills, deaths, best streak, how long
each one ran - with tonight at the top. Your best one is picked
out. That is what "tonight passes your best night" above means,
and what !best tells your chat.

You do not have to do anything for this. It writes itself to
sessions.json next to overlay.exe while you play.


----------------------------------------------------------------
STEP 8 - PUT IT ON YOUR OWN SCREEN, WITHOUT OBS
----------------------------------------------------------------

You do not need OBS at all. The same scoreboards can float over
your game on your own monitor.

On the control page, under "HUDs over the game", tick any of the
panels to float it over the game, and use the arrow buttons to
move each one where you want it. Tick as many as you like - each
is its own little window - and "No HUD" turns them all off.

Any of the seven scoreboards can go there, the same ones you can
put in OBS. It is drawn by the overlay rather than by a browser,
so it shows the same rows the browser ones do, with lists cut to
five, and each panel grows or shrinks to fit what it holds.

It floats above the game and clicks go straight through it, so it
cannot get in your way and cannot be dragged - which is why the
arrows are there.

One requirement: run DAoC in BORDERLESS WINDOWED mode. A true
fullscreen game draws over everything, including this.


----------------------------------------------------------------
STEP 9 - LET IT DRIVE OBS OR STREAMLABS (OPTIONAL)
----------------------------------------------------------------

Everything so far shows numbers. This part presses buttons in
your streaming program for you, so a good moment gets clipped
while it is happening instead of being something you go looking
for afterwards.

It works with OBS and with Streamlabs Desktop. You pick which one
on the control page, and everything else is the same.

Three things it can do, and you pick which:

  * You get several kills quickly     -> save a replay clip
  * You die                           -> switch to another scene
  * You pass a realm point total      -> show a graphic for a
                                         few seconds

All three start switched off. Nothing happens until you set them
up.

FIRST, TURN THE DOOR ON.

  IF YOU USE OBS:
    Tools -> WebSocket Server Settings.
    Tick "Enable WebSocket Server". Click "Show Connect Info"
    and note the Server Port (usually 4455) and the Password.
    Click OK.

  IF YOU USE STREAMLABS DESKTOP:
    Settings -> Remote Control.
    Click the QR code, then "Show details", and copy the API
    token. That token is the password here.

  Either one is a normal feature of that program. It lets
  another program on your own PC ask it to do something.

THEN, FILL IT IN ON THE CONTROL PAGE.

  Open http://localhost:8752/control and find the section
  "Act on it in OBS or Streamlabs".

  1. Tick the box at the top to switch it on.
  2. Program: pick OBS or Streamlabs Desktop. The address box
     fills itself in for the one you pick.
  3. Address: leave it alone unless your program told you a
     different port.
  4. Password (OBS) or API token (Streamlabs): paste what you
     copied. Leave the OBS password empty if OBS has none.
  5. Fill in only the rules you want:

     Save a replay clip after   [3] kills within [30s]
        The replay buffer has to be running for this to save
        anything, and the overlay starts it for you when you
        set this rule. If you stop it yourself it stays
        stopped. The line under this section says what it did.

        If OBS says it cannot start one, the replay buffer is
        switched off in OBS: Settings -> Output. Turn it on
        there and it will work.

     When I die, switch to scene  [ ]
        Type the scene name EXACTLY as it appears in your
        program, capitals and all. Leave empty to switch this
        rule off.

     Every [50000] realm points, show source [ ] in scene [ ]
        Make the graphic first: add an image, a video, or your
        Streamlabs alert as a source in a scene, then untick its
        eye so it is hidden. Put that source's name and its
        scene's name here. The overlay shows it, waits a few
        seconds, and hides it again.

  6. Click Save.

WHAT YOU SHOULD SEE: the little status line in that section
changes within a few seconds from "off" to "armed - 2 rules, 0
fired", or tells you plainly what went wrong. You do not need to
restart anything.

If it says "nothing is listening", the program is closed, or the
door you opened above is not open. If it says the password or the
token is wrong, copy it again from the same place.

ONE STREAMLABS QUIRK: if you use Studio Mode, a scene change
lands in preview rather than on air, and you still transition it
yourself. That is how Streamlabs works, and this program does not
override it - cutting your live output is your call, not its.

A NOTE ON IT BEING TWITCHY: it will not be. There is a 20 second
floor between any two actions, so a good fight gives you one clip
rather than a scene flickering in front of your viewers. And a
long break resets the realm point count, so yesterday's evening
does not count toward tonight's graphic.

If your streaming program runs on your SECOND PC, put that PC's
address in instead of 127.0.0.1, like ws://192.168.1.30:4455.
This is the overlay calling the program, so it is the opposite
direction from step 4.


----------------------------------------------------------------
STEP 10 - LET YOUR CHAT ASK FOR THE NUMBERS (OPTIONAL)
----------------------------------------------------------------

Viewers ask the same questions all night. "How much have you
made?" "How far to your next rank?" This answers them, in your
Twitch chat, so you do not have to.

Somebody types this          It says something like
  !run                       This run: 12,430 RP in 1h42m
                             (7,300/hr) - 14 kills, 3 deaths
  !rp                        ... 1,204,882 lifetime - RR6L2 -
                             170,118 to go
  !kills                     kills, deaths, streak, who you
                             fought most
  !dps                       damage dealt and taken, hit rate
  !pve                       level, xp per hour, coin, zone

All off until you tick them.

FIRST, GET A TOKEN.

  A token is how Twitch knows the messages are allowed to come
  from your account. Search for a "Twitch chat OAuth token
  generator", sign in with the account you want the messages to
  come from, and copy what it gives you. It starts with oauth:

  You can use your own account, or make a second account so the
  answers show up under a bot name. Either works.

  Keep the token to yourself. It is like a password for that
  account.

THEN FILL IT IN.

  On http://localhost:8752/control find "Answer chat".

  1. Tick the box at the top.
  2. Channel: your channel name.
  3. Sends as: the account name the token belongs to.
  4. Token: paste it in.
  5. Tick the commands you want. Untick the rest.
  6. Calls itself: a name if you want one. Put something here
     and every answer starts with it, which helps if your chat
     already has another bot in it. Leave it empty and the
     answers start with the numbers.
  7. Click Save.

WHAT YOU SHOULD SEE: the status line changes to "answering 5
commands, 0 so far" within a few seconds. Type !rp in your own
chat to check it.

If it says the token has expired, generate a new one - they do
expire, and it is not a sign anything is broken.

ABOUT !rp AND YOUR REALM RANK: your chat.log never says what
your lifetime realm point total is. /stats looks like it would
and does not - read its first line and it says "this session".
So !rp says the total is unknown until you switch on step 11,
which is the one that knows it.

IT ONLY READS. There is no command that changes your scene, moves
anything, or touches the game, and nothing anyone types in chat
gets repeated back. The worst a room full of trolls can do is ask
how many realm points you have, slowly - there is a cooldown on
that too.


----------------------------------------------------------------
STEP 11 - YOUR LIFETIME REALM POINTS (OPTIONAL)
----------------------------------------------------------------

Your chat log does not contain your realm point total. It counts
what you earn while it is running, and that is all it can do.
/stats does not help: it counts the session too.

The game's own website does know. The Camelot Herald keeps a
public record of every character, and it says where your total
stood the last time you logged off. This reads that once, then
adds tonight's realm points to it - so the total is right all
evening, and !rp can tell your chat your realm rank and how far
the next one is.

  On http://localhost:8752/control find "Lifetime realm points".

  1. Tick the box.
  2. Character: leave it empty. It uses whoever /stats named and
     fills the full name in for you. Type it in yourself if you
     would rather not wait, or if somebody else on your cluster
     has the same first name as you.
  3. Cluster: Ywain, unless you know otherwise.
  4. Click Save.

WHAT YOU SHOULD SEE: within about fifteen seconds the status
line changes to your full character name, your server, and your
realm points when you last logged off.

If it says it is waiting for the log to name your character,
type /stats in game once.

If it says it found more than one character, two people share
your first name. It lists them both - put your full name,
surname and all, in the Character box.

THIS IS THE ONE THING HERE THAT LEAVES YOUR COMPUTER, which is
why it is off until you tick it. It sends one character name and
one cluster name to the game's own website - exactly what the
Herald page does when anybody looks a character up, at a record
anybody can already read. Nothing from your log, your PC or your
session goes with it, and it asks once when you start playing,
not on a timer.


----------------------------------------------------------------
IF OBS IS ON A SECOND PC
----------------------------------------------------------------

Very common for streamers. The overlay answers only your own PC
unless you tell it otherwise.

  1. Close overlay.exe.
  2. On the control page, tick "Let other machines on my network
     reach the widgets", press Save, then start it again.
     (Or make a shortcut with -lan on the end of the target.)
  3. It now prints a different address, something like
     http://192.168.1.20:8752/w/all
  4. Use THAT address in OBS on the streaming PC, not localhost.
     "localhost" means "this computer", so on the second PC it
     points at the wrong machine.
  5. Allow it through the Windows firewall on Private networks
     when asked.

The settings page is read-only when you open it from the other
PC, on purpose - the settings belong to the machine the game is
on.


----------------------------------------------------------------
THE ICON BY THE CLOCK
----------------------------------------------------------------

While overlay.exe is running there is an icon down by the Windows
clock. Right-click it for:

  * the control page
  * show or hide the HUD
  * end the fight
  * start a new session
  * show or hide the black window
  * quit

PUTTING THE BLACK WINDOW AWAY.

Once you have read the addresses out of it, the black window is
just a window in your way. Minimise it and it goes down to the
clock instead of sitting in the taskbar - still running, still
counting, out of sight. Double-click the icon by the clock to get
it back, or right-click and choose "Show the black window".

If minimising leaves it in the taskbar as normal, your PC is set
to open consoles in Windows Terminal, which is not a window this
program is allowed to put away. Nothing is broken; the window
simply stays where it is.

Three of those also work as keyboard shortcuts, and they work
while you are IN THE GAME - you do not have to alt-tab:

  Ctrl+Alt+H   show or hide the HUD
  Ctrl+Alt+N   start a new session
  Ctrl+Alt+F   end the fight

"Start a new session" sets every number back to zero and begins
again. Use it when you sit down to stream if the overlay has been
open all day, or when you switch to a different character or
group and want the numbers to be about this one.

"End the fight" is a smaller thing. The combat widget counts the
fight you are in as well as the whole night, and it works out
where one fight ends on its own - a minute and a half with no
fighting in the log. That is right nearly always. It is wrong
when you pull, regroup, or run one fight straight into the next,
and this key is for those: press it and the counter starts again
from the next swing.

If a minute and a half is not how you play, change it: on the
control page, under "The fight counter", there is a box for how
long the quiet has to be. Anything from 5s to 30m, and it takes
effect straight away.

IF A SHORTCUT DOES NOTHING, ANOTHER PROGRAM HAS IT.

Windows hands a key combination to whichever program asked for it
first, and it will not tell you which one. So all three shortcuts
are yours to change: open the control page, find "Shortcuts", and type
another combination into the box.

  * one or more of Ctrl, Alt, Shift, Win, then a letter, a digit
    or F1 to F24, with + between them - like Ctrl+Alt+K
  * leave a box empty to turn that shortcut off
  * click Apply and press it - it works straight away, no restart

Beside each box is a word saying what happened:

  working                     the key does what it says
  in use by another program   pick a different combination
  off                         that box is empty
  needs -tray                 started with -tray=false

The menu by the clock does the same two things either way.


----------------------------------------------------------------
TEN MINUTES BEFORE YOU GO LIVE
----------------------------------------------------------------

Six checks, in this order. Two minutes once you know them. Do
them with the game running and yourself logged in.

1. START A FRESH SESSION.

   Every number on the scoreboard counts from the start of the
   session. So if the overlay has been sitting open since
   breakfast, breakfast is in tonight's numbers. Press Ctrl+Alt+N
   (or whatever you set that shortcut to), or right-click the icon
   by the clock and choose "Start a new session". Closing the black
   window and opening it again does the same thing.

   RIGHT LOOKS LIKE: a black window listing your addresses, and
   scoreboards showing zeroes.

2. THE LOG IS ON.

   Open http://localhost:8752/ in a browser.

   RIGHT LOOKS LIKE: the word "Working".

   Anything else, that page says which of the four problems it
   is and step 5 explains all four. The usual one after a patch
   day is the 16 tickboxes coming back unticked - check them
   even when the page looks happy, if the game updated today.

3. THE FLUSHER IS RUNNING, IF YOU USE IT.

   On http://localhost:8752/control, the "Keep the numbers
   moving" section.

   RIGHT LOOKS LIKE: a green pill that starts with the word
   "running" and a count of seconds that goes up when you look
   again.

   Stopped, and your numbers will freeze for minutes and then
   jump - which looks broken on camera even though nothing is.

4. THE SCOREBOARDS ARE LIVE IN OBS.

   Look at the OBS preview, not at the browser. A browser source
   remembers the page it loaded last time.

   RIGHT LOOKS LIKE: the scoreboard is there, and its status
   line says the numbers are live.

   If it is blank or stale: right-click the source and choose
   "Refresh cache of current page". Do this any time you have
   changed a setting since last stream.

5. THE OPTIONAL HALVES REPORT THEMSELVES.

   Skip whichever of these you do not use. Read the pills on
   the control page rather than trusting memory - a Twitch token
   expires quietly and the first you hear of it is chat asking
   why the bot is dead.

   RIGHT LOOKS LIKE:
     Answer chat        "answering 5 commands, 0 so far"
     Lifetime realm     your full character name, your server,
     points             and a realm point total
     Scene director     "armed", and how many rules

   Type !rp in your own chat as the actual proof.

6. THE SETTINGS PAGE IS NOT ON SCREEN.

   http://localhost:8752/control is the one window here that has
   secrets typed into it: your Twitch token and your OBS
   password, in boxes, in plain text.

   RIGHT LOOKS LIKE: no browser tab showing /control in any
   captured window, and no /control tab open at all if you
   capture a whole monitor - Alt-Tab is how it ends up on
   stream.

   Everything else here is safe on camera. The scoreboards show
   your own numbers, and the killfeed shows the names of people
   you killed, which is what the game already puts in everyone
   else's chat box.

IF SOMETHING BREAKS MID-STREAM: the scoreboards keep whatever
they last knew rather than blanking out, so nothing on screen
suddenly empties. Open http://localhost:8752/ on your phone or
your second PC and it will tell you which of the four things went
wrong.


----------------------------------------------------------------
IT IS NOT WORKING
----------------------------------------------------------------

Everything shows zero
    Almost always step 3 part B, the 16 tickboxes. Open
    http://localhost:8752/ and see which of the four states it
    reports.

Nothing appears in OBS at all
    Check overlay.exe is still running - the black window has to
    stay open. Then check the address is exactly right, including
    the http:// at the front.

Numbers freeze for minutes, then jump
    Normal with the flusher off. See step 6.

A number shows a dash instead of a figure
    Nothing has happened yet that it could honestly count. DPS
    and Hit rate stay dashed until you have swung at something,
    and Zone until you walk through a zone line. They fill in on
    their own. A dash is the overlay being careful, not broken.

RP / hour shows a dash
    On purpose, early on. A rate worked out from one kill is
    wrong by miles - one kill a few minutes in reads several
    times the pace you actually end up at. So it waits for five
    kills and five minutes, or twenty minutes on its own if the
    fights are not coming, whichever happens first. Solo roaming
    counts: you do not have to find five fights to get a number,
    you just have to be twenty minutes in. It fills in on its
    own. !run and !rp leave the rate out until then too.

Numbers stopped completely
    /chatlog was probably switched off, or the game was closed.
    Type /chatlog in game again.

Some things count and others do not
    /rp and /xp in game each switch off that kind of reward. With
    them off the game never awards any, so there is nothing to
    count. Type "/rp on" or "/xp on".

Windows will not let you delete chat.log
    The overlay is reading it. Close overlay.exe first. The game
    can still write to it while the overlay runs - only deleting
    and renaming are blocked.

OBS never reacts, even though you set step 9 up
    The status line in "Act on it in OBS" tells you which of the
    two it is. If it is connected and still nothing happens: a
    scene or source name has to match OBS exactly, capitals
    included, and the replay rule needs the replay buffer
    already running in OBS.

Chat commands do nothing
    Check the status line under "Answer chat". If it signed in
    fine, check the command is ticked and that people are typing
    the right prefix. Answers are also on a cooldown, so asking
    twice in a row only gets one answer.

The second PC cannot connect
    See the second-PC section above. Nine times in ten it is the
    firewall prompt that got declined.


----------------------------------------------------------------
WHAT IT DOES AND DOES NOT DO
----------------------------------------------------------------

  * Reads one text file the game writes, when you have asked the
    game to write it.
  * Asks OBS to save a clip or change a scene, but only if you
    switched that on yourself in step 9. It talks to OBS on your
    own PC.
  * Answers commands in your Twitch chat, but only if you
    switched that on yourself in step 10, and only with numbers
    it worked out from your own log.
  * Asks the game's own public website for one character's realm
    point total, but only if you switched that on yourself in
    step 11. It sends a character name and a cluster name and
    nothing else.
  * The flusher, if you turn it on, reads a little of your own
    character from the running game - name, zone, realm rank - and
    tells the game to write its log in real time. That is a
    temporary nudge to the running game; it undoes itself when you
    close the game.
  * Changes no file the game keeps on disk, and never plays for
    you. Nothing it does affects anyone else's game.
  * Nothing leaves your computer except the three things you
    switch on yourself: what it says to OBS, what it says in your
    own Twitch chat, and one character name asked of the game's
    own website. No telemetry, no update check, and no other
    server involved.
  * Your chat log stays on your machine. It is read, never copied
    and never uploaded.

The full technical documentation is in README.md, in the same
folder, if you ever want it. You do not need it for any of the
above.
